feat(cli): replace the cartesi-machine spawn with @cartesi/machine - #509

Contributes to #72.

That issue asks for the external programs the CLI drives to stop being spawned binaries, and notes that "instead of spawning binaries another possibility is to build NodeJS bindings to native code components". This PR takes that route for the emulator.

xgenext2fs gets the same treatment in #517, stacked on this branch. mksquashfs, cartesi-rollups-cli and cartesi-rollups-node are untouched by either, so the remaining work on #72 is the Node Unit's binaries.

What changed

src/machine.ts — the substantial part. The CLI used to hand cartesi-machine a command line and let it assemble the machine configuration. It now does that translation itself, transcribed from cartesi-machine.lua v0.21.0:

• default dtb.bootargs from the emulator, with machine.boot_args appended
• dtb.init: the splash, then dev=$(flashdrive <label>) + mount + chown per non-root drive, then dev=$(nvram <label>) + chmod 0664 + chown per nvram, then export K="V", WORKDIR, USER — in the order the old argv produced
• flash drives with root first, so it lands on /dev/pmem0 regardless of the order drives appear in cartesi.toml
• nvram ranges in declaration order, since that decides the /dev/uio* device each one gets, sized from size or derived from the backing image
• virtio console, console=hvc1 and iunrep=1 for cartesi shell

buildMachineConfig is a pure function so this is unit-testable without running a machine; src/exec/cartesi-machine.ts holds the run loop (automatic yields acknowledged, console I/O resumed, guest exit code read from htif_tohost_data).

src/images.ts (new) — with no SDK image to take linux.bin from, the default ram_image is fetched from the pinned cartesi/machine-linux-image v0.21.0 release on first use, verified against its SHA-256 and cached under $XDG_CACHE_HOME/cartesi/images. A CARTESI_IMAGES_PATH directory holding the image is used when set, and machine.ram_image still wins over both.

Console capture — bootMachine grew a captureOutput option. There is no child process to read stdout from any more, and the emulator exposes no API to read a captured console back, so it writes to a temporary file that the run reads once it is over. This is what keeps tests/integration/machine/nvram.test.ts able to assert on what the guest printed.

Breaking

• Machine hashes change. @cartesi/machine links against emulator 0.21, the SDK image pins 0.20. Applications need redeploying.
• A snapshot is read by the linked emulator. cartesi hash and cartesi status no longer run cartesi-machine-stored-hash in the project's SDK image, so a snapshot stored by an incompatible emulator reads as no hash and has to be rebuilt. getMachineHash lost its sdk option accordingly, which also drops the now-unused sdk plumbing through run's interactive shell.
• Boot args are no longer double quoted. The old code passed --append-bootargs="<arg>" with no shell in between, so the quotes ended up in the kernel command line. Building the configuration directly, reproducing that would have meant reproducing a bug.
• The standalone binaries are gone. A Bun single-file executable has no node_modules, and the addon resolves its platform .node at runtime — a host-native --compile fails too, so cross-compiling four targets was never going to work. The compile step in build.ts and the upload step in release.yaml are removed here. The homebrew formula in cartesi/homebrew-tap needs to install from npm rather than the release tarball. Happy to revert this bit and solve distribution differently if you'd rather keep the binaries.

Rebased onto the nvram and version-check work

The base moved 61 commits while this sat, and a few of them built directly on the code this replaces, so the update was a port rather than a conflict resolution:

• nvrams (fdfd3c1, 81fedfc, a3cfe1f, 81e6157, bb31cfe, 5fd7421) went in as --nvram= flags. They are now nvram memory ranges in the machine configuration, with the init lines the emulator's own CLI generates for them. Resolving the conflict without porting this would have silently dropped nvram support.
• the version check (481cc2f, fdd6d93, f48d0a3, c9878d6, 5493e17) probed cartesi-machine --version-json through Docker. requiredVersion, UnsupportedVersionError and assertSupported are kept as they were — they still guard that the linked emulator is in range — while version() is now a local lookup, and assertVersion() takes no options. The unit tests for them are kept, and doctor reports the compiled-in version instead of probing an install.
• @cartesi/machine@alpha moved from 1.0.0-alpha.0 to 1.0.0-alpha.2, which returns hashes as Uint8Array rather than Buffer; those are converted with viem's bytesToHex.

Testing

• 234 unit tests pass. tests/unit/machine.test.ts covers the configuration translation (mount points, drive ordering, nvram sizing and ordering, nvram init lines, environment precedence, workdir/user, interactive mode, parseMemorySize); the base branch's nvram cases are carried over as assertions on the configuration rather than on argv.
• Verified against the real emulator that it accepts the generated nvram ranges, that the init script matches the Lua reference, and that captureOutput returns the guest console.
• cartesi-machine-stored-hash.test.ts keeps the base branch's isHash assertion, on the new signature. Its "with the project sdk image" case is gone, since hashing no longer involves an image; the replacement asserts getMachineHash() resolves the project snapshot.

Not verified locally: a successful rollup application boot and the nvram integration tests, which need Docker with riscv64. CI covers those.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UTEd5g3mF849BATTstssR3